gate(spec): register packages/spec/src/** doc blocks as the fourth symbol-anchor corpus, censused first - #17241

Clause-②: no

Fixes #17065

Registers packages/spec/src/** doc blocks as the fourth corpus of the shared symbol-anchor resolver — a defineCorpus call in the deliberately thin shape check-adr-symbol-anchors.mjs and check-scripts-symbol-anchors.mjs already use. ⛔ No second resolver — the 2026-09-01 ruling on #13556 forbids one in terms, and scripts/symbol-anchors.mjs is untouched by this diff.

⭐ The census came first, and here is the number

The card wrote the order hard and it was followed literally: register, run the reporting arms, take the count, then choose the exit contract. Measured on 08e38c6377 over the 1,317 tracked .ts files under packages/spec/src, with the instrument named beside every number because three instruments give three answers on one tree:

Total hard findings: 7 across 6 of 1,317 files — the 6 line anchors plus 1 unresolved-path. Alongside them: 183 citations naming no tracked file (69 bare-filename, 62 directory-qualified, 52 continuation, across 34 files), and 3 soft cross-repo-skipped rows.

Controls, because a small number needs them more than a big one does. Every zero here is backed by a same-corpus positive control, using short fragments only:

• counts.symbol is 0. Control: git grep for a backticked path-hash-identifier span across packages/spec/src returns exactly 1 file — api/websocket.zod.ts — and that one span is the unresolved-path finding. So the zero is "the convention has not reached this corpus", not "the extractor matched nothing".
• The extractor is demonstrably live on this corpus: 2,639 anchors across 1,317 sources, 2,635 of them file-level.
• The declined count is enumerated, not just counted: --list-unresolvable prints all 183 rows, and the self-test holds declined.length equal to the counter.

The bare-path axis, measured for the checkBarePaths: false call: 2,635 bare path spans; 346 name a tracked file at the repo root, 610 resolve only when prefixed with packages/spec/src/ (spec doc blocks habitually cite package-relative), and 1,679 (758 distinct) bind against neither base. Judging them would produce 2,290 findings — the same call docs/adr/** made at 1,056 and scripts/** at 1,617.

The exit contract that number justified, and why

A pinned day-one residual, with the gate ON. All 7 findings live in packages/spec/** text, which this card ⛔ forbids this lane from editing — repairing a spec doc block is domain:spec work with its own cards. That left two honest options: a gate that can never fail, or a gate that fails on everything except a dated, enumerated, shrink-only residual.

A gate that can never fail is the verifier AGENTS.md names as worse than no verifier, so CENSUS_RESIDUAL pins the 7 sites with their repairs and every finding outside it is a hard red from day one — which is exactly the property the card asked for: the fourth set does not have to be found by hand.

⛔ It is not an exemption list. It is exact in both directions: a row whose citation gets repaired goes stale and reds until it is deleted, so a repair forces the row out in the same PR. Rows are keyed by citation text, never by line — a line-keyed row would be a line anchor inside the line-anchor gate, rotting the first time anyone added a paragraph above it.

⚠️ Re-grade triggers: both measured, neither fires — with one caveat that belongs to the PM

Trigger 1 (rot comparable to 72.1%, or a count that makes this a migration): does NOT fire. 7 findings across 6 of 1,317 files is a gate, not a migration.

⚠️ But that answer is conditional on the scope call, and the conditionality is the reading rather than a footnote to it. With judgeUntrackedLineAnchors flipped to true, the same tree yields 189 findings on day one — which would be a migration. The small number is not a claim that spec doc blocks are clean; it is a statement about the citations a resolver living in this repo can bind. Both numbers are pinned in CENSUS_17065 and the self-test holds them consistent, so the reassuring one can never be read without the other.

Trigger 2 (a fifth hand-repair filed before this lands): does NOT fire. Searched with a positive control that the search reaches this very card (#17065 came back in the results); the open cards in this family are #16960 (the third repair) and #15809 (the scripts/** declined-citation worklist). No fifth.

⭐ An honest limit of this gate, stated because it is the card's own subject

The three objectql/engine.ts:NNNN sites that #16960 owns are written with an abbreviated path, so they name no tracked file and land in the declined set — this gate would not have caught them. Same for the record-validator.ts sites #16441 repaired. The fourth set this registration stops from being found by hand is the set written with a repo-root path.

That is not a defect in the registration — it is the same scope call scripts/** made, whose residual became #15809 — but it would be dishonest to let the header imply otherwise, so the header says it in those words and --list-unresolvable keeps the population a worklist rather than a number. Handed to the PM below rather than carded here.

Verification

Ablation — the gate really can fail, both directions, on the live tree. Each leg: on-disk mutation proven by occurrence counts and a changed blob hash, run, restore proven byte-identical against the HEAD blob. ⛔ No packages/spec/** text was touched by either leg — both mutate the gate's own CENSUS_RESIDUAL, which is what decides the exit contract.

Derived gates. node scripts/pm/dispatch-gates.mjs --commands derived 63 families from the changeset; all 63 were run and reconciled with --ran: "63 derived famil(ies) accounted for — 63 run, 0 NOT-MEASURED."

One derived gate went genuinely red and was repaired: check-scripts-symbol-anchors — scripts/** is itself a corpus, so the new gate's own header quoting a broken anchor verbatim made this file a finding. Both offending spellings are now described in words, with the reason stated inline. Both corpora are green on the final commit.

Five commands exit 3 = PREREQUISITE NOT MET and are NOT MEASURED, not red — they read dist/ and want a full pnpm build: check:dts-closure, check:dual-build-cjs-loads, check:lean-entry-closure, check:sourcemap-no-sources-content, check:type-check-debt. This diff touches no package source, so no package closure is affected; the full build belongs to CI.

Re-run on the final commit 0be9a49284: both symbol-anchor corpora plus their self-tests, the ADR corpus, the shared resolver's self-test, check-step-collectors, check-self-test-workflow-commands, check-self-test-wired, check:nul-bytes, check:parse-guard, check:declared-population-live, check:watch-hint-literal, check:type-check-coverage — all exit 0. check:pm-dispatch-gates (the tool whose ledger prose this diff edits) passes: "dispatch-gates self-test: 1624 cases pass."

Lint, as a declared narrowing rather than a repo-wide run. Targeted eslint --no-inline-config --format json over the 2 changed .mjs files: 2 files linted, 0 errors, 0 warnings. The three pieces of evidence the narrowing needs: ① the population is read from eslint.config.mjs itself, which lints only from the root; ② the file count is read from --format json output, not asserted; ③ the invariance claim is the config's own measured declaration — it "never enables type-aware linting (no parserOptions.project, no typed @typescript-eslint rules) for ANY file" — so this diff cannot move the verdict on any file it did not touch. The repo-wide pnpm lint remains CI's run.

skip-changeset, measured with a positive control. Nothing published moves: 70 published packages inspected, 0 name scripts/ or lint.yml in files[]; the control is that all 70 name dist, proving the probe reads real entries. The root manifest is private: true. All four paths are fast-track — repo-root config, .github/workflows/, scripts/**, scripts/pm/**.

Acceptance notes — found, not fixed

• The 183 declined citations are a real population no open card covers (the scripts/** analogue, [finding] 96 of the 128 line citations in scripts/** gate headers name no tracked file, so the new symbol-anchor corpus declines them by name #15809, is scoped to that corpus only). They include the three sites [finding] three objectql/engine.ts:NNNN anchors in the doc block #16441 just repaired are off by up to 5,677 lines — outside that card's census, so they survived it #16960 owns. Enumerated by --list-unresolvable so a follow-up can be closed rather than re-measured. Handed to the PM rather than carded from this lane.
• The resolver's repo: prefix is a bare lowercase word, so any bare-word-colon-path labelling convention inside a TypeScript doc block reads as a cross-repo anchor. shared/retired-key-migrate-sentence.test.ts documents its own corpus labels that way and lands 3 soft rows. Soft is the correct disposition — reported, never red — so this is a noted boundary, not a defect, and not filed.
• packages/spec/liveness/** and the rest of packages/spec outside src/ are outside this corpus. docPattern is .ts under packages/spec/src; the liveness ledger's citations are JSON and are gated separately by check:liveness.

Not addressed here

⛔ Out of scope: #16962 remains open — that card's @example caption convention is a different convention with no existing mechanism, deliberately not merged with this one. #16960 remains open and lands on its own; this PR ⛔ does not repair its three sites, and does not repair the 7 pinned residual sites either.

Generated by Claude Code